Skip to content

Commit 9606637

Browse files
TieskeTieske
authored
release 1.0.0 (#19)
1 parent cf3b88f commit 9606637

File tree

13 files changed

+1111
-280
lines changed

13 files changed

+1111
-280
lines changed

‎.luacov

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
modules = {
2-
["uuid.*"] = "src"
1+
include = {
2+
"src%/.+$",
33
}
44

55
runreport = true

‎CHANGELOG.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ The scope of what is covered by the version number excludes:
3030

3131
## Version history
3232

33-
### Version 1.0.0, unreleased
33+
### Version 1.0.0, released 13-Oct-2024
3434

3535
- BREAKING: no default rng will be picked anymore, one must be set explicitly, see `set_rng`
3636
- BREAKING: calling on the module table `uuid()` will now call `v4()` instead of `new()`
@@ -44,10 +44,11 @@ The scope of what is covered by the version number excludes:
4444
additional input for seeding the Lua rng (eg. pass in a mac address).
4545
- Feat: new `rng.luasystem` rng that uses LuaSystem for random number generation (Posix + Windows)
4646
- Feat: new `rng.urandom` rng that uses /dev/urandom for random number generation (Posix, no Windows)
47+
- Feat: new `rng.win_ffi` rng that uses the ffi for random number generation (Windows, no Posix)
4748
- Feat: new `rng.math_random` rng that replaces the old rng used, based on Lua's `math.random` function.
48-
- Feat: improved seeding, using LuaSystem, or /dev/urandom if available. If not, the fallback now uses
49+
- Feat: improved seeding, using LuaSystem, win-ffi, or /dev/urandom if available. If not, the fallback now uses
4950
more inputs (including a user provided one, eg. a mac address) and calculates a SHA1 used as seed.
50-
Also support for the Lua 5.4
51+
Also support for the Lua 5.4 `randomseed()` implementation
5152

5253
### Version 0.3, released 11-Jul-2021
5354

‎LICENSE.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -188,7 +188,7 @@
188188
same "printed page" as the copyright notice for easier
189189
identification within third-party archives.
190190
191-
Copyright 2012 Rackspace, 2013-2021 Thijs Schreijer
191+
Copyright 2012 Rackspace, 2013-2024 Thijs Schreijer
192192
193193
Licensed under the Apache License, Version 2.0 (the "License");
194194
you may not use this file except in compliance with the License.

‎docs/index.html

Lines changed: 28 additions & 179 deletions
Original file line numberDiff line numberDiff line change
@@ -27,211 +27,60 @@
2727
<h1>uuid</h1>
2828

2929

30-
<h2>Contents</h2>
31-
<ul>
32-
<li><a href="#Functions">Functions</a></li>
33-
</ul>
30+
3431

3532

3633
<h2>Modules</h2>
3734
<ul class="nowrap">
38-
<li><strong>uuid</strong></li>
35+
<li><a href="modules/uuid.html">uuid</a></li>
36+
<li><a href="modules/uuid.rng.html">uuid.rng</a></li>
3937
</ul>
4038
<h2>Topics</h2>
4139
<ul class="">
42-
<li><a href="topics/readme.md.html">readme</a></li>
40+
<li><a href="topics/01-introduction.md.html">1. Introduction</a></li>
41+
<li><a href="topics/CHANGELOG.md.html">CHANGELOG</a></li>
42+
<li><a href="topics/LICENSE.md.html">Apache 2.0 License</a></li>
4343
</ul>
4444

4545
</div>
4646

4747
<div id="content">
4848

49-
<h1>Module <code>uuid</code></h1>
50-
<p>Copyright 2012 Rackspace (original), 2013-2021 Thijs Schreijer (modifications)</p>
51-
52-
<p> Licensed under the Apache License, Version 2.0 (the "License");
53-
you may not use this file except in compliance with the License.</p>
54-
<p> You may obtain a copy of the License at</p>
55-
56-
57-
<pre>
58-
http://www.apache.org/licenses/LICENSE-<span class="number">2.0</span>
59-
</pre>
60-
61-
<p> Unless required by applicable law or agreed to in writing, software
62-
distributed under the License is distributed on an "AS-IS" BASIS,
63-
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
64-
See the License for the specific language governing permissions and
65-
limitations under the License.</p>
66-
67-
<p> see http://www.ietf.org/rfc/rfc4122.txt</p>
6849

69-
<p> Note that this is not a true version 4 (random) UUID. Since <code>os.time()</code> precision is only 1 second, it would be hard
70-
to guarantee spacial uniqueness when two hosts generate a uuid after being seeded during the same second. This
71-
is solved by using the node field from a version 1 UUID. It represents the mac address.</p>
50+
<h2>Module to generate uuids in pure Lua</h2>
7251

73-
<p> 28-apr-2013 modified by Thijs Schreijer from the original <a href="https://github.com/kans/zirgo/blob/807250b1af6725bad4776c931c89a784c1e34db2/util/uuid.lua">Rackspace code</a> as a generic Lua module.
74-
Regarding the above mention on <code>os.time()</code>; the modifications use the <code>socket.gettime()</code> function from LuaSocket
75-
if available and hence reduce that problem (provided LuaSocket has been loaded before uuid).</p>
76-
77-
<p> <strong>Important:</strong> the random seed is a global piece of data. Hence setting it is
78-
an application level responsibility, libraries should never set it!</p>
79-
80-
<p> See this issue; <a href="https://github.com/Kong/kong/issues/478">https://github.com/Kong/kong/issues/478</a>
81-
It demonstrates the problem of using time as a random seed. Specifically when used from multiple processes.
82-
So make sure to seed only once, application wide. And to not have multiple processes do that
83-
simultaneously.</p>
84-
85-
86-
<h2><a href="#Functions">Functions</a></h2>
87-
<table class="function_list">
52+
<h2>Modules</h2>
53+
<table class="module_list">
8854
<tr>
89-
<td class="name" nowrap><a href="#new">new (hwaddr)</a></td>
90-
<td class="summary">Creates a new uuid.</td>
55+
<td class="name" nowrap><a href="modules/uuid.html">uuid</a></td>
56+
<td class="summary">Copyright 2012 Rackspace (original), 2013-2024 Thijs Schreijer (modifications)</td>
9157
</tr>
9258
<tr>
93-
<td class="name" nowrap><a href="#randomseed">randomseed (seed)</a></td>
94-
<td class="summary">Improved randomseed function.</td>
59+
<td class="name" nowrap><a href="modules/uuid.rng.html">uuid.rng</a></td>
60+
<td class="summary">Random number generator utilities with different properties and uses.</td>
9561
</tr>
62+
</table>
63+
<h2>Topics</h2>
64+
<table class="module_list">
9665
<tr>
97-
<td class="name" nowrap><a href="#seed">seed ()</a></td>
98-
<td class="summary">Seeds the random generator.</td>
66+
<td class="name" nowrap><a href="topics/01-introduction.md.html">01-introduction.md</a></td>
67+
<td class="summary"></td>
68+
</tr>
69+
<tr>
70+
<td class="name" nowrap><a href="topics/CHANGELOG.md.html">CHANGELOG.md</a></td>
71+
<td class="summary"></td>
72+
</tr>
73+
<tr>
74+
<td class="name" nowrap><a href="topics/LICENSE.md.html">LICENSE.md</a></td>
75+
<td class="summary"></td>
9976
</tr>
10077
</table>
10178

102-
<br/>
103-
<br/>
104-
105-
106-
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
107-
108-
<dl class="function">
109-
<dt>
110-
<a name = "new"></a>
111-
<strong>new (hwaddr)</strong>
112-
</dt>
113-
<dd>
114-
115-
<p>Creates a new uuid. Either provide a unique hex string, or make sure the
116-
random seed is properly set. The module table itself is a shortcut to this
117-
function, so <code>my_uuid = uuid.new()</code> equals <code>my_uuid = uuid()</code>.</p>
118-
119-
<p> For proper use there are 3 options;</p>
120-
121-
<ol>
122-
<li>first require <code>luasocket</code>, then call <code>uuid.seed()</code>, and request a uuid using no
123-
parameter, eg. <code>my_uuid = uuid()</code></li>
124-
<li>use <a href="index.html#">uuid</a> without <code>luasocket</code>, set a random seed using <code>uuid.randomseed(some_good_seed)</code>,
125-
and request a uuid using no parameter, eg. <code>my_uuid = uuid()</code></li>
126-
<li>use <a href="index.html#">uuid</a> without <code>luasocket</code>, and request a uuid using an unique hex string,
127-
eg. <code>my_uuid = uuid(my_networkcard_macaddress)</code></li>
128-
</ol>
129-
130-
131-
132-
133-
<h3>Parameters:</h3>
134-
<ul>
135-
<li><span class="parameter">hwaddr</span>
136-
(optional) string containing a unique hex value (e.g.: <code>00:0c:29:69:41:c6</code>), to be used to compensate for the lesser <code>math_random()</code> function. Use a mac address for solid results. If omitted, a fully randomized uuid will be generated, but then you must ensure that the random seed is set properly!
137-
</li>
138-
</ul>
139-
140-
<h3>Returns:</h3>
141-
<ol>
142-
143-
a properly formatted uuid string
144-
</ol>
145-
146-
147-
148-
<h3>Usage:</h3>
149-
<ul>
150-
<pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span>(<span class="string">"uuid"</span>)
151-
<span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
152-
</ul>
153-
154-
</dd>
155-
<dt>
156-
<a name = "randomseed"></a>
157-
<strong>randomseed (seed)</strong>
158-
</dt>
159-
<dd>
160-
Improved randomseed function.
161-
Lua 5.1 and 5.2 both truncate the seed given if it exceeds the integer
162-
range. If this happens, the seed will be 0 or 1 and all randomness will
163-
be gone (each application run will generate the same sequence of random
164-
numbers in that case). This improved version drops the most significant
165-
bits in those cases to get the seed within the proper range again.
166-
167-
168-
<h3>Parameters:</h3>
169-
<ul>
170-
<li><span class="parameter">seed</span>
171-
the random seed to set (integer from 0 - 2^32, negative values will be made positive)
172-
</li>
173-
</ul>
174-
175-
<h3>Returns:</h3>
176-
<ol>
177-
178-
the (potentially modified) seed used
179-
</ol>
180-
181-
182-
183-
<h3>Usage:</h3>
184-
<ul>
185-
<pre class="example"><span class="keyword">local</span> socket = <span class="global">require</span>(<span class="string">"socket"</span>) <span class="comment">-- gettime() has higher precision than os.time()
186-
</span><span class="keyword">local</span> uuid = <span class="global">require</span>(<span class="string">"uuid"</span>)
187-
<span class="comment">-- see also example at uuid.seed()
188-
</span>uuid.randomseed(socket.gettime()*<span class="number">10000</span>)
189-
<span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
190-
</ul>
191-
192-
</dd>
193-
<dt>
194-
<a name = "seed"></a>
195-
<strong>seed ()</strong>
196-
</dt>
197-
<dd>
198-
Seeds the random generator.
199-
It does so in 3 possible ways;</p>
200-
201-
<ol>
202-
<li>if in ngx_lua, use <code>ngx.time() + ngx.worker.pid()</code> to ensure a unique seed
203-
for each worker. It should ideally be called from the <code>init_worker</code> context.</li>
204-
<li>use luasocket <code>gettime()</code> function, but it only does so when LuaSocket
205-
has been required already.</li>
206-
<li>use <code>os.time()</code>: this only offers resolution to one second (used when
207-
LuaSocket hasn't been loaded)</li>
208-
</ol>
209-
210-
<p> <strong>Important:</strong> the random seed is a global piece of data. Hence setting it is
211-
an application level responsibility, libraries should never set it!
212-
213-
214-
215-
216-
217-
218-
<h3>Usage:</h3>
219-
<ul>
220-
<pre class="example"><span class="keyword">local</span> socket = <span class="global">require</span>(<span class="string">"socket"</span>) <span class="comment">-- gettime() has higher precision than os.time()
221-
</span><span class="comment">-- LuaSocket loaded, so below line does the same as the example from randomseed()
222-
</span>uuid.seed()
223-
<span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
224-
</ul>
225-
226-
</dd>
227-
</dl>
228-
229-
23079
</div> <!-- id="content" -->
23180
</div> <!-- id="main" -->
23281
<div id="about">
233-
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
234-
<i style="float:right;">Last updated 2021-07-11 08:59:24 </i>
82+
<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
83+
<i style="float:right;">Last updated 2024-10-13 00:59:03 </i>
23584
</div> <!-- id="about" -->
23685
</div> <!-- id="container" -->
23786
</body>

‎docs/ldoc.css

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
body {
1+
body {
22
color: #47555c;
33
font-size: 16px;
44
font-family: "Open Sans", sans-serif;

0 commit comments

Comments
 (0)